
/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2020原作者。
 *
 *根据Apache许可证2.0版（“许可证”）许可；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，否则软件
 *根据许可证分发是在“按原样”的基础上分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可证下的限制。
 */

package org.springframework.context.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.springframework.beans.factory.support.BeanNameGenerator;
import org.springframework.core.annotation.AliasFor;
import org.springframework.core.type.filter.TypeFilter;

/**
 * Configures component scanning directives for use with @{@link Configuration} classes.
 * Provides support parallel with Spring XML's {@code <context:component-scan>} element.
 *
 * <p>Either {@link #basePackageClasses} or {@link #basePackages} (or its alias
 * {@link #value}) may be specified to define specific packages to scan. If specific
 * packages are not defined, scanning will occur from the package of the
 * class that declares this annotation.
 *
 * <p>Note that the {@code <context:component-scan>} element has an
 * {@code annotation-config} attribute; however, this annotation does not. This is because
 * in almost all cases when using {@code @ComponentScan}, default annotation config
 * processing (e.g. processing {@code @Autowired} and friends) is assumed. Furthermore,
 * when using {@link AnnotationConfigApplicationContext}, annotation config processors are
 * always registered, meaning that any attempt to disable them at the
 * {@code @ComponentScan} level would be ignored.
 *
 * <p>See {@link Configuration @Configuration}'s Javadoc for usage examples.
 *
 * @author Chris Beams
 * @author Juergen Hoeller
 * @author Sam Brannen
 * @since 3.1
 * @see Configuration
 */
/**
 *配置与@｛@link Configuration｝类一起使用的组件扫描指令。
 *提供与Spring XML的｛@code＜context:component scan＞｝元素并行的支持。
 *
 *<p>｛@link#basePackageClasses｝或｛@link#basePackages｝（或其别名
 *｛@link#value｝）来定义要扫描的特定包。如果具体
 *未定义程序包，将从的程序包进行扫描
 *声明此注释的类。
 *
 *＜p＞请注意，｛@code＜context:component scan＞｝元素有一个
 *｛@code annotation config｝属性；然而，这个注释没有。这是因为
 *在几乎所有情况下，当使用｛@code@ComponentScan｝时，默认的注释配置
 *假设处理（例如处理{@code@Autowired}和朋友）。此外
 *当使用｛@link AnnotationConfigApplicationContext｝时，注释配置处理器是
 *始终注册，这意味着在
 *｛@code@ComponentScan｝级别将被忽略。
 *
 *＜p＞有关用法示例，请参阅｛@link Configuration@Configuration｝的Javadoc。
 *
 *@作者Chris Beams
 *@作者Juergen Hoeller
 *@作者Sam Brannen
 *@自3.1起
 *@请参阅配置
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Repeatable(ComponentScans.class)
public @interface ComponentScan {

	/**
	 * Alias for {@link #basePackages}.
	 * <p>Allows for more concise annotation declarations if no other attributes
	 * are needed &mdash; for example, {@code @ComponentScan("org.my.pkg")}
	 * instead of {@code @ComponentScan(basePackages = "org.my.pkg")}.
	 */
	/**
	 *｛@link#basePackages｝的别名。
	 *＜p＞如果没有其他属性，则允许更简洁的注释声明
	 *是必需的&mdash；例如，{@code@ComponentScan（“org.my.pkg”）}
	 *而不是{@code@ComponentScan（basePackages=“org.my.pkg”）}。
	 */
	@AliasFor("basePackages")
	String[] value() default {};

	/**
	 * Base packages to scan for annotated components.
	 * <p>{@link #value} is an alias for (and mutually exclusive with) this
	 * attribute.
	 * <p>Use {@link #basePackageClasses} for a type-safe alternative to
	 * String-based package names.
	 */
	/**
	 *要扫描带注释组件的基本包。
	 *＜p＞｛@link#value｝是此的别名（与互斥）
	 *属性。
	 *＜p＞使用｛@link#basePackageClasses｝作为
	 *基于字符串的包名称。
	 */
	@AliasFor("value")
	String[] basePackages() default {};

	/**
	 * Type-safe alternative to {@link #basePackages} for specifying the packages
	 * to scan for annotated components. The package of each class specified will be scanned.
	 * <p>Consider creating a special no-op marker class or interface in each package
	 * that serves no purpose other than being referenced by this attribute.
	 */
	/**
	 *键入｛@link#basePackages｝的安全替代方案以指定包
	 *以扫描带注释的组件。将扫描指定的每个类别的包。
	 *<p>考虑在每个包中创建一个特殊的无操作标记类或接口
	 *除了被该属性引用之外，没有其他用途。
	 */
	Class<?>[] basePackageClasses() default {};

	/**
	 * The {@link BeanNameGenerator} class to be used for naming detected components
	 * within the Spring container.
	 * <p>The default value of the {@link BeanNameGenerator} interface itself indicates
	 * that the scanner used to process this {@code @ComponentScan} annotation should
	 * use its inherited bean name generator, e.g. the default
	 * {@link AnnotationBeanNameGenerator} or any custom instance supplied to the
	 * application context at bootstrap time.
	 * @see AnnotationConfigApplicationContext#setBeanNameGenerator(BeanNameGenerator)
	 * @see AnnotationBeanNameGenerator
	 * @see FullyQualifiedAnnotationBeanNameGenerator
	 */
	/**
	 *用于命名检测到的组件的｛@link BeanNameGenerator｝类
	 *在Spring容器中。
	 *＜p＞｛@link BeanNameGenerator｝接口本身的默认值指示
	 *用于处理此｛@code@ComponentScan｝注释的扫描仪应该
	 *使用其继承的bean名称生成器，例如默认的
	 *｛@link AnnotationBeanNameGenerator｝或提供给
	 *引导时的应用程序上下文。
	 *@参见AnnotationConfigApplicationContext#setBeanNameGenerator（BeanNameGenerator）
	 *@参见AnnotationBeanNameGenerator
	 *@请参阅FullyQualifiedAnnotationBeanNameGenerator
	 */
	Class<? extends BeanNameGenerator> nameGenerator() default BeanNameGenerator.class;

	/**
	 * The {@link ScopeMetadataResolver} to be used for resolving the scope of detected components.
	 */
	/**
	 *用于解析检测到的组件的作用域的｛@link ScopeMetadataResolver｝。
	 */
	Class<? extends ScopeMetadataResolver> scopeResolver() default AnnotationScopeMetadataResolver.class;

	/**
	 * Indicates whether proxies should be generated for detected components, which may be
	 * necessary when using scopes in a proxy-style fashion.
	 * <p>The default is defer to the default behavior of the component scanner used to
	 * execute the actual scan.
	 * <p>Note that setting this attribute overrides any value set for {@link #scopeResolver}.
	 * @see ClassPathBeanDefinitionScanner#setScopedProxyMode(ScopedProxyMode)
	 */
	/**
	 *指示是否应为检测到的组件生成代理，这些组件可能
	 *以代理样式的方式使用作用域时是必要的。
	 *＜p＞默认值是根据用于
	 *执行实际扫描。
	 *<p>请注意，设置此属性将覆盖为{@link#scopeResolver}设置的任何值。
	 *@see ClassPathBeanDefinitionScanner#setScopedProxyMode（ScopedProxyMode）
	 */
	ScopedProxyMode scopedProxy() default ScopedProxyMode.DEFAULT;

	/**
	 * Controls the class files eligible for component detection.
	 * <p>Consider use of {@link #includeFilters} and {@link #excludeFilters}
	 * for a more flexible approach.
	 */
	/**
	 *控制符合组件检测条件的类文件。
	 *<p>考虑使用{@link#includeFilters}和{@link#excludeFilters}
	 *以获得更灵活的方法。
	 */
	String resourcePattern() default ClassPathScanningCandidateComponentProvider.DEFAULT_RESOURCE_PATTERN;

	/**
	 * Indicates whether automatic detection of classes annotated with {@code @Component}
	 * {@code @Repository}, {@code @Service}, or {@code @Controller} should be enabled.
	 */
	/**
	 *指示是否自动检测用｛@code@Component｝注释的类
	 *应启用{@code@Repository}、{@code@Service}或{@code@Controller}。
	 */
	boolean useDefaultFilters() default true;

	/**
	 * Specifies which types are eligible for component scanning.
	 * <p>Further narrows the set of candidate components from everything in {@link #basePackages}
	 * to everything in the base packages that matches the given filter or filters.
	 * <p>Note that these filters will be applied in addition to the default filters, if specified.
	 * Any type under the specified base packages which matches a given filter will be included,
	 * even if it does not match the default filters (i.e. is not annotated with {@code @Component}).
	 * @see #resourcePattern()
	 * @see #useDefaultFilters()
	 */
	/**
	 *指定哪些类型有资格进行组件扫描。
	 *＜p＞从｛@link#basePackages｝中的所有内容进一步缩小候选组件集
	 *到基本包中与给定的一个或多个筛选器匹配的所有内容。
	 *<p>请注意，如果指定了这些过滤器，则除了默认过滤器之外，还会应用这些过滤器。
	 *将包括与给定过滤器匹配的指定基本包下的任何类型，
	 *即使它与默认过滤器不匹配（即没有用{@code@Component}进行注释）。
	 *@参见#resourcePattern（）
	 *@请参阅#useDefaultFilters（）
	 */
	Filter[] includeFilters() default {};

	/**
	 * Specifies which types are not eligible for component scanning.
	 * @see #resourcePattern
	 */
	/**
	 *指定哪些类型不符合组件扫描条件。
	 *@参见#resourcePattern
	 */
	Filter[] excludeFilters() default {};

	/**
	 * Specify whether scanned beans should be registered for lazy initialization.
	 * <p>Default is {@code false}; switch this to {@code true} when desired.
	 * @since 4.1
	 */
	/**
	 *指定是否应注册扫描的bean以进行延迟初始化。
	 *＜p＞默认值为｛@code false｝；根据需要将其切换为{@code true}。
	 *@自4.1起
	 */
	boolean lazyInit() default false;


	/**
	 * Declares the type filter to be used as an {@linkplain ComponentScan#includeFilters
	 * include filter} or {@linkplain ComponentScan#excludeFilters exclude filter}.
	 */
	/**
	 *声明要用作｛@linkplain ComponentScan#includeFilters的类型筛选器
	 *包含筛选器｝或｛@linkplain ComponentScan#excludeFilters排除筛选器｝。
	 */
	@Retention(RetentionPolicy.RUNTIME)
	@Target({})
	@interface Filter {

		/**
		 * The type of filter to use.
		 * <p>Default is {@link FilterType#ANNOTATION}.
		 * @see #classes
		 * @see #pattern
		 */
		/**
		 *要使用的筛选器类型。
		 *<p>默认值为｛@link FilterType#ANNOTATION｝。
		 *@见#classes
		 *@见#图案
		 */
		FilterType type() default FilterType.ANNOTATION;

		/**
		 * Alias for {@link #classes}.
		 * @see #classes
		 */
		/**
		 *｛@link#classes｝的别名。
		 *@见#classes
		 */
		@AliasFor("classes")
		Class<?>[] value() default {};

		/**
		 * The class or classes to use as the filter.
		 * <p>The following table explains how the classes will be interpreted
		 * based on the configured value of the {@link #type} attribute.
		 * <table border="1">
		 * <tr><th>{@code FilterType}</th><th>Class Interpreted As</th></tr>
		 * <tr><td>{@link FilterType#ANNOTATION ANNOTATION}</td>
		 * <td>the annotation itself</td></tr>
		 * <tr><td>{@link FilterType#ASSIGNABLE_TYPE ASSIGNABLE_TYPE}</td>
		 * <td>the type that detected components should be assignable to</td></tr>
		 * <tr><td>{@link FilterType#CUSTOM CUSTOM}</td>
		 * <td>an implementation of {@link TypeFilter}</td></tr>
		 * </table>
		 * <p>When multiple classes are specified, <em>OR</em> logic is applied
		 * &mdash; for example, "include types annotated with {@code @Foo} OR {@code @Bar}".
		 * <p>Custom {@link TypeFilter TypeFilters} may optionally implement any of the
		 * following {@link org.springframework.beans.factory.Aware Aware} interfaces, and
		 * their respective methods will be called prior to {@link TypeFilter#match match}:
		 * <ul>
		 * <li>{@link org.springframework.context.EnvironmentAware EnvironmentAware}</li>
		 * <li>{@link org.springframework.beans.factory.BeanFactoryAware BeanFactoryAware}
		 * <li>{@link org.springframework.beans.factory.BeanClassLoaderAware BeanClassLoaderAware}
		 * <li>{@link org.springframework.context.ResourceLoaderAware ResourceLoaderAware}
		 * </ul>
		 * <p>Specifying zero classes is permitted but will have no effect on component
		 * scanning.
		 * @since 4.2
		 * @see #value
		 * @see #type
		 */
		/**
		 *要用作筛选器的一个或多个类。
		 *<p>下表解释了如何解释类
		 *基于{@link#type}属性的配置值。
		 *<表格border=“1”>
		 *<tr><th>｛@code FilterType｝</th><th>类解释为</th></tr>
		 *<tr><td>｛@link过滤器类型#注释注释注释｝</td>
		 *<td>注释本身</td></tr>
		 *<tr><td>｛@link过滤器类型#ASSIGNABLE_TYPE ASSIGNABLE_TYPE｝</td>
		 *<td>检测到的组件应可分配给</td></tr>的类型
		 *<tr><td>｛@link过滤器类型#CUSTOM CUSTOM｝</td>
		 *<td>｛@link TypeFilter｝的实现</td></tr>
		 *</表格>
		 *<p>当指定多个类时，应用<em>OR</em>逻辑
		 *&mdash；例如，“包括用｛@code@Foo｝或｛@code@Bar｝注释的类型”。
		 *＜p＞自定义｛@link TypeFilter TypeFilters｝可以选择性地实现
		 *以下｛@link org.springframework.beans.factory.Aware Aware｝接口，以及
		 *它们各自的方法将在{@link TypeFilter#match match}之前被调用：
		 *＜ul＞
		 *<li>｛@link org.springframework.context.EnvironmentAware环境感知｝</li>
		 *＜li＞｛@link org.springframework.beans.factory.BeanFactory软件BeanFactory软件｝
		 *<li>｛@link org.springframework.beans.factory.BeanClassLoaderAware BeanClassLoader Aware｝
		 *<li>｛@link org.springframework.context.ResourceLoaderAware资源加载器Aware｝
		 *</ul>
		 *＜p＞允许指定零类，但对组件没有影响
		 *扫描。
		 *@自4.2起
		 *@见#值
		 *@见#类型
		 */
		@AliasFor("value")
		Class<?>[] classes() default {};

		/**
		 * The pattern (or patterns) to use for the filter, as an alternative
		 * to specifying a Class {@link #value}.
		 * <p>If {@link #type} is set to {@link FilterType#ASPECTJ ASPECTJ},
		 * this is an AspectJ type pattern expression. If {@link #type} is
		 * set to {@link FilterType#REGEX REGEX}, this is a regex pattern
		 * for the fully-qualified class names to match.
		 * @see #type
		 * @see #classes
		 */
		/**
		 *作为替代方案，用于过滤器的模式
		 *到指定类｛@link#值｝。
		 *<p>如果将{@link#type}设置为{@linkFilterType#ASPECTJ ASPECTJ}，
		 *这是一个AspectJ类型的模式表达式。如果｛@link#type｝为
		 *设置为｛@link FilterType#REGEX REGEX｝，这是一个正则表达式模式
		 *以匹配完全限定的类名。
		 *@见#类型
		 *@见#classes
		 */
		String[] pattern() default {};

	}

}
